Interstitial

warning

This is the documentation for the Advanced API. Most developers should use our Simplified API (documented in Interstitial), which comes with several built-in features such as:

• Automatic ad loading
• Retries for failed requests
• Simplified lifecycle management

Only use the Advanced API if you need fine-grained control over the ad loading and presentation lifecycle.

The Advanced API provides direct access to individual Interstitial instances, giving you complete control over when and how ads are loaded and presented.

An interstitial ad is a fullscreen format, usually skippable after the first few seconds of its display. Because of this, it's commonly used in transitions of the app or game, such as completing a level or navigating to a different screen.

Create an Interstitial instance

var interstitial = Interstitial.Create("<placement-id>");

Register ad callbacks

// Load Callbacks
interstitial.OnPrebiddingFinished += result => {
    Debug.Log("Interstitial client-side bidding finished!");
};

interstitial.OnLoaded += result => {
    Debug.Log("Interstitial loaded!");
};

interstitial.OnFailedToLoad += (error, result) => {
    Debug.Log($"Interstitial failed to load. Reason: {error.Message}");
};

// Show Callbacks
interstitial.OnShowed += () => {
    Debug.Log("Interstitial is being shown!");
};

interstitial.OnFailedToShow += error => {
    // If you need to resume your app's flow, make sure to do it here and in the OnDismissed callback
    Debug.Log($"Interstitial failed to show. Reason: {error.Message}");
};

interstitial.OnImpression += impressionData => {
    Debug.Log("Interstitial impression!");
};

interstitial.OnDismissed += () => {
    // If you need to resume your app's flow, make sure to do it here and in the OnFailedToShow callback
    Debug.Log("Interstitial dismissed! Resume gameplay");
};

info

For information about handling callback threads using XMediatorMainThreadDispatcher please refer to Sanitize Callback Threads.

Load an ad

interstitial.Load();

Load an ad (with custom properties)

interstitial.Load(
    customProperties: new CustomProperties.Builder()
        .AddString("game_mode", "classic")
        .Build()
);

Show an ad

if (interstitial.IsReady()) {
    interstitial.Show("interstitial-ad-space");
}

Dispose an ad

interstitial.Dispose();

Complete example

InterstitialTest.cs

using JetBrains.Annotations;
using UnityEngine;
using UnityEngine.UI;
using XMediator.Api;

namespace X3M.XMediatorTest.Scripts
{
    public class InterstitialTest : MonoBehaviour
    {
        public Button CreateButton;
        public Button LoadButton;
        public Button ShowButton;

        [CanBeNull] private Interstitial _interstitial;

        private void Start()
        {
            CreateButton.onClick.AddListener(OnCreateClicked);
            LoadButton.onClick.AddListener(OnLoadClicked);
            ShowButton.onClick.AddListener(OnShowClicked);
        }

        private void OnDestroy()
        {
            // Dispose the interstitial at the end of its lifecycle
            _interstitial?.Dispose();
        }

        private void OnCreateClicked()
        {
            Log("Create button clicked.");

            // Dispose previous interstitial instance
            _interstitial?.Dispose();

            // Create an interstitial instance
            _interstitial = Interstitial.Create("<placement-id>");

            // Load Callbacks
            _interstitial.OnPrebiddingFinished += result => XMediatorMainThreadDispatcher.Enqueue(
                () => { Log("Interstitial client-side bidding finished!"); }
            );

            _interstitial.OnLoaded += result => XMediatorMainThreadDispatcher.Enqueue(
                () => { Log("Interstitial loaded!"); }
            );

            _interstitial.OnFailedToLoad += (error, result) => XMediatorMainThreadDispatcher.Enqueue(
                () => { Log($"Interstitial failed to load. Reason: {error.Message}"); }
            );

            // Show Callbacks
            _interstitial.OnShowed += () => { Log("Interstitial is being shown!"); };

            _interstitial.OnFailedToShow += error => { Log($"Interstitial failed to show. Reason: {error.Message}"); };

            _interstitial.OnImpression += impressionData => { Log("Interstitial impression!"); };

            _interstitial.OnDismissed += () => { Log("Interstitial dismissed! Resume gameplay"); };
        }

        private void OnLoadClicked()
        {
            Log("Load button clicked.");
            _interstitial?.Load();
        }

        private void OnShowClicked()
        {
            Log("Show button clicked.");
            if (_interstitial != null && _interstitial.IsReady())
            {
                _interstitial.Show("interstitial-ad-space");
            }
        }

        private static void Log(string message)
        {
            Debug.Log($"[InterstitialTest] {message}");
        }
    }
}